home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Diamond Collection / The Diamond Collection (Software Vault)(Digital Impact).ISO / cdr29 / cadq_010.zip / CADQUTIL.DOC < prev    next >
Text File  |  1995-03-16  |  10KB  |  222 lines
  1.                               CADQUTIL Version 0.1
  2.              Client Access/400 Data Queues OS/2 REXX Utility Libary
  3.  
  4. CADQUTIL is an OS/2 REXX external function library that uses the AS/400
  5. Client Access Data Queues APIs.  Support for most of the high-level
  6. data queue APIs is provided, with the exception of asynchronous receiving
  7. of a data queue message.
  8.  
  9. Because the utility provides a REXX interface to the Client Access APIs,
  10. it should be able to be used from within graphical REXX packages such as
  11. Watcom's VX-REXX to provide an easier client/server interface for
  12. OS/2-AS/400 graphical applications.
  13.  
  14. The library was created using Client Access/400 V3R1M0 data queue APIs
  15. and may or may not run with prior or future versions of OS/400 or
  16. Client Access/400.
  17.  
  18. The contents of this package are:
  19.  
  20. CADQUTIL.DOC - Data queues utility function documentation (this file).
  21. CADQUTIL.DLL - Data queues REXX function library.
  22. TESTDQ.CMD   - Sample REXX program for a non-keyed data queue.
  23. TESTDQK.CMD  - Sample REXX program for a keyed data queue.
  24.  
  25. =================================  DISCLAIMER =================================
  26.  
  27. The CADQUTIL REXX library and all accompanying documentation and examples
  28. are provided on an "AS IS" basis. This means that Innovative Systems Design
  29. does not warrant, guarantee, or make any other representations regarding
  30. the use, or results of use, of the library functions or documentation in
  31. terms of accuracy, reliability, correctness, or otherwise. Innovative Systems
  32. Design will not be held responsible for any direct, indirect, incidental,
  33. or consequential damages including damages for loss of business profits,
  34. business interruption, loss of business information, or otherwise arising
  35. from the use or inability to use this product, even if Inovative Systems
  36. Design has been advised of the possibility of such damages.
  37.  
  38. ================================= REGISTRATION ===============================
  39.  
  40. The CADQUTIL library is distributed as shareware and may be freely
  41. distributed as long as all the above files are included and are unmodified.
  42.  
  43. If after thirty days you find the product useful and can no longer ignore
  44. your conscience, you should register it.
  45.  
  46. The registration fee is $25 US for an individual CPU or $100 US for a
  47. full site license, and may be submitted through cash, check (drawn on
  48. a U.S. bank) money order or international money order.
  49.  
  50. Please include your name, company name, address, e-mail address and
  51. the version number from the top of this document to:
  52.  
  53.   Innovative Systems Design
  54.   23011 Moulton Parkway, Suite E-10
  55.   Laguna Hills, CA 92653
  56.  
  57. Comments, questions, suggestions and yes, bug reports can be submitted
  58. via the internet to gregt@isd.realm.net (CompuServe users can use
  59. INTERNET:gregt@isd.realm.net).
  60.  
  61. ============================ INSTALLATION AND USAGE ===========================
  62.  
  63. To install the function library, unzip the contents of this package
  64. into a directory in your LIBPATH.
  65.  
  66. To use the functions, you must be using any flavor of OS/2 2.1 or later with
  67. REXX support installed.  OS/2 Client Access/400 must be started (with
  68. data queues support installed) and the OS/2 PC Support directory must be in
  69. your LIBPATH.
  70.  
  71. The first thing you'll need to do in the REXX procedure is load the
  72. function library.  This is done by including the following lines before
  73. any calls to the utility functions:
  74.  
  75.   call rxfuncadd 'CADQLoadFuncs', 'CADQUTIL', 'CADQLoadFuncs'
  76.   call CADQLoadFuncs
  77.  
  78. The utility functions supported are defined below.  They can be coded in a
  79. REXX command file as functions (returning a value) or as called procedures.
  80. Unless otherwise noted, the REXX variable RESULT will contain the return
  81. code from the corresponding Client Access API.  For more information,
  82. refer to the Client Access/400 API reference manual.
  83.  
  84. Note: All parameters are positional and must appear in the order shown.
  85. Optional parameters are shown in brackets [] and must include a comma
  86. placeholder if omitted from the middle of the list. If omitted from the
  87. end of the list, trailing commas should not be present.
  88.  
  89. ===============================================================================
  90. CADQCreate: Create Data Queue
  91.  
  92. Usage: call CADQCreate q-name,[sys-name],max-q-length,seq,force,aut,sender,
  93.                        [q-text],[key-length]
  94.  
  95. Parameters:
  96.   q-name:       Data queue name in AS/400 notation (library/name).
  97.   sys-name:     System name. If not specified, the default system is used.
  98.   max-q-length: Maximum data queue message length.
  99.   seq:          Sequence. 0=LIFO, 1=FIFO.  Ignored for keyed data queues.
  100.   force:        Force data to storage. 0=No, 1=Yes
  101.   aut:          Data queue authority. 0=*ALL, 1=*EXCLUDE, 2=*CHANGE,
  102.                                       3=*USE, 4=*LIBCRTAUT
  103.   sender:       Include sender ID with message. 0=No, 1=Yes
  104.   text:         Data queue text description (optional).
  105.   key-length:   If specified, indicates the key length for a keyed data
  106.                 queue.  If omitted, a non-keyed data queue will be created.
  107.  
  108. ===============================================================================
  109. CADQDelete: Delete Data Queue
  110.  
  111. Usage: call CADQDelete q-name,[sys-name]
  112.  
  113. Parameters:
  114.   q-name:       Data queue name in AS/400 notation (library/name).
  115.   sys-name:     System name. If not specified, the default system is used.
  116.  
  117. ===============================================================================
  118. CADQClear: Clear Data Queue
  119.  
  120. Usage: call CADQClear q-name,[sys-name]
  121.  
  122. Parameters:
  123.   q-name:       Data queue name in AS/400 notation (library/name).
  124.   sys-name:     System name. If not specified, the default system is used.
  125.  
  126. ===============================================================================
  127. CADQPut: Put Data to a Queue without waiting for a reply.
  128.  
  129. Usage: call CADQPut q-name,[sys-name],data,[key-value]
  130.  
  131. Parameters:
  132.   q-name:       Data queue name in AS/400 notation (library/name).
  133.   sys-name:     System name. If not specified, the default system is used.
  134.   data:         Message to be queued.
  135.   key-value:    Key value for the message to be enqueued.
  136.                 Required for a keyed queue, not allowed for a non-keyed queue.
  137. ===============================================================================
  138. CADQSend: Send Data to a Queue and wait for a reply.
  139.  
  140. Usage: call CADQSend q-name,[sys-name],data,[key-value]
  141.  
  142. Parameters:
  143.   q-name:       Data queue name in AS/400 notation (library/name).
  144.   sys-name:     System name. If not specified, the default system is used.
  145.   data:         Message to be queued.
  146.   key-value:    Key value for the message to be enqueued.
  147.                 Required for a keyed queue, not allowed for a non-keyed queue.
  148. ===============================================================================
  149. CADQReceive: Receive Data from a Queue and wait for a reply.
  150.  
  151. Usage: call CADQReceive q-name,[sys-name],wait,data-var,data-len,[sender-var],
  152.                         [key-value,srch-ord,[key-var,key_len]]
  153.  
  154. Parameters:
  155.   q-name:       Data queue name in AS/400 notation (library/name).
  156.   sys-name:     System name. If not specified, the default system is used.
  157.   wait:         Receive wait time in seconds.
  158.   data-var:     Name of a REXX variable to receive the queued message.
  159.   dat-len:      Maximum length of the message to receive.
  160.   sender-var:   Name of a REXX variable to recieve the sender ID.
  161.                 If omitted, the sender ID is not returned.
  162.   key-value:    Key value to search for (keyed queue only).
  163.   srch-ord:     Key search order (EQ NE GT GE LT LE) (keyed queue only).
  164.   key-var:      Name of a REXX variable for the key value received.
  165.                 If omitted, the actual key value will not be returned.
  166.   key-len:      Length of the received key value.
  167.  
  168. ===============================================================================
  169. CADQSetMode: Set Data Queues Mode.
  170.  
  171. Usage: call CADQSetMode [sys-name],[xlate],[peek]
  172.  
  173. Parameters:
  174.   sys-name:     System name. If not specified, the default system is used.
  175.   xlate:        Translation mode. 0=No, 1=Yes, omitted=no change
  176.   peek:         Peek mode.        0=No, 1=Yes, omitted=no change
  177.  
  178. ===============================================================================
  179. CADQGetMsg: Get Message.
  180.  
  181. Usage: call CADQGetMsg [sys-name]
  182.  
  183. Parameters:
  184.   sys-name:     System name. If not specified, the default system is used.
  185.  
  186. The REXX variable RESULT will contain the retrieved message.  If no more
  187. messages are available, the length of RESULT will be 0.
  188.  
  189. ===============================================================================
  190. CADQQuery: Query Data Queue
  191.  
  192. Usage: call CADQQuery q-name,[sys-name]
  193.  
  194. Parameters:
  195.   q-name:       Data queue name in AS/400 notation (library/name).
  196.   sys-name:     System name. If not specified, the default system is used.
  197.  
  198. The following REXX variables will be set:
  199.  
  200.   DQ_MAXLEN:    Maximum length of messages for the specified queue.
  201.   DQ_SEQ:       Sequence indicator for a non-keyed queue.
  202.   DQ_FORCE:     Force data indicator.
  203.   DQ_SENDER     Sender ID indicator.
  204.   DQ_TEXT:      Text description for the queue.
  205.   DQ_KEYLEN:    Key length for a keyed queue.
  206.  
  207. ===============================================================================
  208. CADQStop: Stop Data Queues
  209.  
  210. Usage: call CADQStop [sys-name]
  211.  
  212. Parameters:
  213.   sys-name:     System name. If not specified, the default system is used.
  214.  
  215. ===============================================================================
  216.  
  217. =============================== REVISION HISTORY ==============================
  218.  
  219. Version 0.1 - 03/16/95
  220.   Initial public beta release.
  221.  
  222.